home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW dmake 4.0 / dbug / malloc / malloc.3 < prev    next >
Encoding:
Text File  |  1995-06-01  |  6.6 KB  |  146 lines  |  [TEXT/MPS ]
  1. .TH MALLOC 3 "" "" "1.0"
  2. .ds ]T 
  3. .\"/*
  4. .\" * (c) Copyright 1990 Conor P. Cahill (uunet!virtech!cpcahil).  
  5. .\" * You may copy, distribute, and use this software as long as this
  6. .\" * copyright statement is not removed.
  7. .\" */
  8. .\" $Id: malloc.3,v 1.3 90/08/29 22:24:44 cpcahil Exp $
  9. .SH NAME
  10. malloc \t- debugging malloc library
  11. .SH SYNOPSIS
  12. .ft B
  13. .nf
  14. #include <malloc.h>
  15.  
  16. char    * calloc(nelem,elsize);
  17. void      free(ptr);
  18. char    * malloc(size);
  19. int      malloc_chain_check(flag);
  20. void      malloc_dump(fd);
  21. int      mallopt(cmd,val)
  22. char    * realloc(ptr,size);
  23.  
  24. int              cmd,fd,flag;
  25. unsigned          elsize,nelem,size;
  26. char            * ptr;
  27. union malloptarg      val;
  28.  
  29. .fi
  30. .ft R
  31. .SH DESCRIPTION
  32. This malloc library is a replacement for the standard library to be used
  33. during software development/debugging.  See the standard malloc(3) pages
  34. for more information on the use of the following functions:
  35. .nf
  36. .in +.5i
  37. calloc(), free(), malloc(), realloc()
  38. .in -.5i
  39. .fi
  40. .sp
  41. This library differs from the standard malloc library in the
  42. following ways:
  43. .P
  44. 1. Each malloc segment contains a magic number so that free can 
  45. verify that the pointer passed points to a valid malloc segment.
  46. .P
  47. 2. Each malloc segment is filled with a non-zero pattern so that code that
  48. depends upon malloc segments being null will fail.
  49. .P
  50. 3. The size of each segment will be at least 1 byte larger than requested
  51. and the extra bytes will be filled with a non-zero pattern.  When free is
  52. called, it will verify that you did not go beyond the number of bytes 
  53. you asked for.
  54. .P
  55. 4. When a segment is freed, it will be filled with a different non-zero pattern
  56. to ensure that the program doesn't depend upon the use of already freed data.
  57. .P
  58. 5. Whenever any of the string or memory functions (str*, b*, mem*) are 
  59. called with a pointer that is within the malloc arena,  the operation is
  60. checked to verify that it does not overrun the malloced segment.  A failure
  61. of this check is considered a "warning level error" (described later) and
  62. is handled accordingly.
  63. .P
  64. 7. Run time checking can include verification of the malloc chain at each
  65. and every call to one of the malloc functions or manually by calling the
  66. malloc_chain_check function.
  67. .P
  68. 6. When a problem is found, the action taken is specified at runtime by
  69. environment variables or at compile time by the use of the mallopt()
  70. function.
  71. .P
  72. There are two arbitrary levels of errors, warning and fatal, that this
  73. library will detect.  They are broken down as follows:
  74. .P
  75. .nf
  76. .in +.25i
  77. Warning messages include:
  78. .sp
  79. .in +.5i
  80. .ti -.25i
  81. Calling free with a bad pointer
  82. .br
  83. .ti -.25i
  84. Calling a bstring/string/memory (3) function which will go beyond
  85. the end of a malloc block. Note that the library function is
  86. not modified to refuse the operation.
  87. .sp
  88. .in -.5i
  89. Fatal errors are:
  90. .in +.5i
  91. .ti -.25i
  92. Detectable corruption to the malloc chain.
  93. .in -.5i
  94. .in -.25i
  95. .P
  96. The error handling for each level (warning or fatal) are specified using
  97. environment variables or mallopt().  The coding for the error handling is
  98. as follows:
  99. .sp
  100. .nf
  101. .in +.5i
  102. .ti -.25i
  103.   0 - continue operations
  104. .ti -.25i
  105.   1 - drop core and exit
  106. .ti -.25i
  107.   2 - just exit
  108. .ti -.25i
  109.   3 - drop core, but continue executing.  Core files will
  110. be placed into core.[PID].[counter] i.e: core.00123.001
  111. .ti -.25i
  112. 128 - dump malloc chain and continue
  113. .ti -.25i
  114. 129 - dump malloc chain, dump core, and exit
  115. .ti -.25i
  116. 130 - dump malloc chain, exit
  117. .ti -.25i
  118. 131 - dump malloc chain, dump core, continue processing
  119. .in -.5i
  120. .P
  121. In addition error messages can be placed into an error file.
  122. .P
  123. \fBmalloc_opt\fP() is used to set the malloc debugging options. The
  124. following options can be set:
  125. .br
  126. .sp
  127. .in +.5i
  128. MALLOC_WARN - set the error handling for warning level errors.  \fBval.i\fP is
  129. an integer that can contain any one of the following values:
  130. .sp
  131. .in +.5i
  132. M_HANDLE_IGNORE - ignore error
  133. .br
  134. M_HANDLE_ABORT - drop core and exit
  135. .br
  136. M_HANDLE_EXIT - just exit (no core drop)
  137. .br
  138. M_HANDLE_CORE - drop core, but keep on going
  139. .br
  140. .in -.5i
  141. .sp
  142. In addition, M_HANDLE_DUMP may be or'd in to cause a dump of the current
  143. malloc chain.
  144. .br
  145. .sp
  146. MALLOC_FATAL - set th